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PREFACE 


Notation 

The notational conventions used in this manual are: 

DIRECTIVE 

All linker directives and options are shown in bold upper case to highlight them. 
However, the linker will recognize both upper and lowercase for options and direc¬ 
tives. 


{} 

Contains a list of elements or directives, one of which must be selected. Each 
choice will be separated by a vertical bar. For example, {R IL} indicates that either 
R or L must be selected. 

[] 


Contains one or more optional elements. If more than one optional element is 
shown, the required element separators are indicated. All elements outside of the 
angle brackets (< >) must be specified as they appear. For example, the syntacti¬ 
cal element [<number>,] requires the comma to be specified if the optional element 
<number> is selected. 
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The element names are printed in lower case and contained in angle brackets. 
Some common elements used to describe linker options are: 


<expr> or 

<expression> 

<number> 

<string> 

<delimiter> 

<option> 

<sym> or 

<symbol> 


A linker expression 
A numeric constant 

A string of ASCII characters enclosed in quotes 
A delimiter character 
A linker option 
A linker symbol 
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Chapter 1 

MOTOROLA DSP LINKER 


1.1 INTRODUCTION 

The Motorola DSP Linker is a program that processes relocatable object files produced 
by the Motorola DSP assemblers, generating an absolute executable file which can be 
loaded directly into one of the Motorola DSP simulators, downloaded to an application de¬ 
velopment system, or converted to Motorola S-record format for PROM burning. A com¬ 
mand line option provides for specification of a base address for each DSP memory space 
and logical location counter (high, low, default). In addition, a memory control file may be 
supplied to indicate absolute positioning of sections in DSP memory as well as physical 
mappings to internal and external memory. The linker optionally generates a map file 
which shows memory assignment of sections by memory space and a sorted list of sym¬ 
bols with their load time values. 

1.2 INSTALLING THE LINKER 

The linker is distributed on various media and in different formats depending on the host 
operating system environment. See Appendix G in the Motorola DSP Assembler Ref¬ 
erence Manual, HOST-DEPENDENT INFORMATION, for details on installing and oper¬ 
ating the linker on your particular machine. 

1.3 RUNNING THE LINKER 

The general format of the command line to invoke the linker is: 

DSPLNK [options] <filenames> 


where: 

[options] 


Any of the following command line options. These can be in any order, but 
must precede the list of source filenames. Some options can be given more 
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than once; the individual descriptions indicate which options may be speci¬ 
fied multiple times. Option letters can be in either upper or lower case. 

Option arguments may immediately follow the option letter or may be sepa¬ 
rated from the option letter by blanks or tabs. However, an ambiguity arises 
if an option takes an optional argument. Consider the following command 
line: 


DSPLNK -B MAIN 10 

In this example it is not clear whether the file MAIN is an input file oris meant 
to be an argument to the -B option. If the ambiguity is not resolved the linker 
will assume that MAIN is an input file and attempt to open it for reading. This 
may not be what the programmer intended. 

There are several ways to avoid this ambiguity. If MAIN is supposed to be 
an argument to the -B option it can be placed immediately after the option 
letter: 


DSPLNK -BMAIN IO 

If there are other options on the command line besides those that take op¬ 
tional arguments the other options can be placed between the ambiguous 
option and the list of input file names: 

DSPLNK -B MAIN -V 10 

An alternative is to use two successive hyphens to indicate the end of the 
option list: 

DSPLNK -B - MAIN 10 

In this latter case the linker interprets MAIN as an input file name and uses 
the default naming conventions for the -B option. 


-B[<objfil>] 


This option specifies that an object file is to be created for linker output. 
<objfil> can be any legal operating system filename, including an optional 
pathname. A hyphen also may be used as an argument to indicate that the 
object file should be sent to the standard output. 

If a pathname is not specified, the file will be created in the current directory. 
If no filename is specified, or if the -B option is not present, the linker will use 
the basename (filename without extension) of the first filename encountered 
in the input file list and append .CLD to the basename. If the -I option is 
present (see below) an explicit filename must be given. This is because if 
the linker followed the default action it possibly could overwrite one of the 
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existing input files. The -B option should be specified only once. If the file 
named in the -B option already exists, it will be overwritten. 

Example: DSPLNK -Bfilter.cld main.cln fft.cln fio.cln 

In this example, the files MAIN.CLN, FFT.CLN, and FIO.CLN are 
linked together to produce the absolute executable file FILTER.CLD. 


F<argfil> 


Indicates that the linker should read command line input from <argfil>. 
<argfil> can be any legal operating system filename, including an optional 
pathname. <argfil> is a text file containing further options, arguments, and 
filenames to be passed to the linker. The arguments in the file need be sep¬ 
arated only by some form of white space (blank, tab, newline). A semicolon 
(;) on a line following white space makes the rest of the line a comment. 

The -F option was introduced to circumvent the problem of limited line 
lengths in some host system command interpreters. It may be used as often 
as desired, including within the argument file itself. 

Example: DSPLNK -Fopts.cmd 

Invoke the linker and take command line options and input filenames 
from the command file OPTS.CMD. 



Send source file line number information to the object file. The generated 
line number information can be used by debuggers to provide source-level 
debugging. 

Example: DSPLNK -B -G myprog.cln 

Link the file MYPROG.CLN and send source file line number infor¬ 
mation to the resulting object file MYPROG.CLD. 



The linker ordinarily produces an absolute executable file as output. When 
the -I option is given the linker combines the input files into a single relocat¬ 
able object file suitable for reprocessing by the linker. No absolute address¬ 
es are assigned and no errors are issued for unresolved external 
references. Note that the -B option must be used when performing incre- 
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mental linking in order to give an explicit name to the output file. If the file¬ 
name were allowed to default it could overwrite an existing input file. 

Example: DSPLNK -I -Bfilter.cln main.cln fft.cln fio.cln 

In this example, the files MAIN.CLN, FFT.CLN, and FIO.CLN are 
combined to produce the relocatable object file FILTER.CLN. 


-L<library> 


The linker ordinarily processes a list of input files which each contain a sin¬ 
gle relocatable code module. If the -L option is encountered the linker treats 
the following argument as a library file and searches the file for any out¬ 
standing unresolved references. 

If a module is found in the library that resolves an outstanding external ref¬ 
erence, the module is read from the library and included in the object file out¬ 
put. The linker continues to search a library until all external references are 
resolved or no more references can be satisfied within the current library. 
The linker searches a library only once, when it is encountered on the com¬ 
mand line. Therefore, the position of the -L option on the command line is 
significant. 

Example: DSPLNK -B filter main fir -Lio 

This example illustrates linking with a library. The files MAIN.CLN 
and FIR.CLN are combined with any needed modules in the library 
IO.LIB to create the file FILTER.CLD. 


-M[<mapfil>] 


This option indicates that a map file is to be created. <mapfil> can be any 
legal operating system filename, including an optional pathname. A hyphen 
also may be used as an argument to indicate that the map file should be 
sent to the standard output. 

If a pathname is not specified, the file will be created in the current directory. 
If no filename is specified, the linker will use the basename (filename without 
extension) of the first filename encountered in the input file list and append 
.MAP to the basename. If the -M option is not specified, then the linker will 
not generate a map file. The -M option should be specified only once. If the 
file named in the -M option already exists, it will be overwritten. 

Example: DSPLNK -M -- filter.cln gauss.cln 

In this example, the files FILTER.CLN and GAUSS.CLN are linked 

together to produce a map file. Because no filename was given with 
the -M option, the output file will be named using the basename of the 
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first input file, in this case FILTER. The map file will be called FIL¬ 
TER. MAP. 



The linker considers case significant in symbol names. When the -N option 
is given the linker ignores case in symbol names; all symbols are mapped 
to lower case. 

Example: DSPLNK -N filter.cln fft.cln fio.cln 

In this example, the files FILTER.CLN, FFT.CLN, and FIO.CLN are 
linked to produce the absolute executable file FILTER.CLD. All sym¬ 
bol references are mapped to lower case. 

0<me m>[<ctr>][<map>] :<o rig i n> 

By default the linker generates instructions and data for the output file be¬ 
ginning at absolute location zero for all DSP memory spaces. This option 
allows the programmer to redefine the start address for any memory space 
and associated location counter. 

<mem> is one of the single-character memory space identifiers (X, Y, L, P). 
The letter may be upper or lower case. The optional <ctr> is a letter indicat¬ 
ing the high (H) or low (L) location counters, if no counter is specified the 
default counter is used. <map> is also optional and signifies the desired 
physical mapping for all relocatable code in the given memory space. It may 
be I for internal memory, E for external memory, R for ROM, A for port A, 
and B for port B. If <map> is not supplied, then no explicit mapping is pre¬ 
sumed. 

The <origin> is a hexadecimal number signifying the new relocation address 
for the given memory space. The -O option may be specified as many times 
as needed on the command line. This option has no effect if incremental 
linking is being done (see the >1 option). 

Example: DSPLNK -Ope:200 myprog -Lmylib 

This will initialize the default P memory counter to hex 200 and map 
the program space to external memory. 


P<pathname> 

When the linker encounters input files, the current directory (or the directory 
given in the library specification) is first searched for the file. If it is not found 
and the -P option is specified, the linker prefixes the filename (and optional 
pathname) of the file specification with <pathname> and searches the newly 
formed directory pathname for the file. 
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The pathname must be a legal operating system pathname. The -P option 
may be repeated as many times as desired. The directories will be searched 
in the order specified on the command line. 

Example: DSPLNK -P\project\ testprog 

This example uses IBM PC pathname conventions, and would cause 
the linker to prefix any library files not found in the current directory 
with the \project\ pathname. 


-R[<ctlfil>] 


This option indicates that a memory control file is to be read to determine 
the placement of sections in DSP memory and other linker control functions. 
<ctlfil> can be any legal operating system filename, including an optional 
pathname. 

If a pathname is not specified, an attempt will be made to open the file in the 
current directory. If no filename is specified, the linker will use the base- 
name (filename without extension) of the first filename encountered in the 
link input file list and append .CTL to the basename. If the -R option is not 
specified, then the linker will not use a memory control file. The -R option 
should be specified only once. 

Example: DSPLNK -Rproj filter.cln gauss.cln 

In this example, the files FILTER.CLN and GAUSS.CLN are linked 
together using the memory file PROJ.CTL. 


-U<symbol> 


Allows the declaration of an unresolved reference from the command line. 
<symbol> must be specified. This option is useful for creating an undefined 
external reference in order to force linking entirely from a library. 

Example: DSPLNK -U start -Lproj.lib 

Declare the symbol START undefined so that it will be resolved by 
code within the library PROJ.LIB. 



This option causes the linker to report linking progress (beginning of passes, 
opening and closing of input files) to the standard error output stream. This 
is useful to insure that link editing is proceeding normally. 

t 

Example: DSPLNK -V myprog.cln 

Link the file MYPROG.CLN and send progress lines to the standard 
error output. 
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X<opt>[, <opt> <opt>] 


The -X option provides for link time options that alter the standard operation 
of the linker. The options are described below. All options may be preceded 
by NO to reverse their meaning. The -X<opt> sequence can be repeated 
for as many options as desired. 


Option 



XC 

RSV 

AEC 

RO 

ESO 

ASC 


Relative terms from different sections used in an 
expression cause an error 
Reserve special target processor memory areas 
(e.g. DSP96000 DMA) 

Check form of address expressions 
Allow region overlap 

Do not allocate memory below ordered sections 
Enable absolute section bounds checking 


Example: DSPLNK -XNOXC myprog.asm 


This will disable checking of relative terms from different sections in 
arithmetic expressions. 



The linker strips source file line number and symbol information from the 
output file. Symbol information normally is retained for debugging purpos¬ 
es. This option has no effect if incremental linking is being done (see the -I 
option). 

Example: DSPLNK -Z filter.cln fft.cln fio.cln 

In this example, the files FILTER.CLN, FFT.CLN, and FIO.CLN are 
linked to produce the absolute object file FILTER.CLD. The output 
file will contain no symbol or line number information. 


<filenames> 


A list of operating system compatible filenames (including optional path¬ 
names). If no extension is supplied for a given file, the linker first will attempt 
to open the file using the filename as supplied. If that is not successful the 
linker appends .CLN to the filename and attempts to open the file again. If 
no pathname is specified for a given file, the linker will look for that file in the 
current directory. The list of files will be processed sequentially in the order 
given and all files will be used to generate the object file and map listing. 

For more details on linker operation in a particular machine environment see Appendix G, 
HOST-DEPENDENT INFORMATION, in the Motorola DSP Assembler Reference Man¬ 
ual. 
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1.4 LINKER OPERATION 


Using a linker allows the programmer to break up a large program into more manageable 

modules which may be assembled or compiled separately. These modules can then be 
link edited to produce an absolute module of the complete program. If a problem arises, 
only the module with the problem need be edited and reassembled. Then the program¬ 
mer can relink the updated relocatable object module and the other previously created ob¬ 
ject modules to produce a new executable file. 

1.4.1 Relocation and Unking 

The input to the linker is a set of relocatable object modules produced by the Motorola 
DSP assembler. The term relocatable means that the data in the module has not yet 
been assigned to absolute addresses in memory; instead, each different section is as¬ 
sembled as though it started at relative address 0 (an exception to this is absolute blocks, 
which do get assigned to absolute addresses at assembly time). When creating an abso¬ 
lute object module, it is the job of the linker to read all the relocatable object modules 
which comprise a program and assign the relocatable blocks in each section to an abso¬ 
lute memory address. Then in the process of actually putting the code and data read from 
each object module into the proper location in the executable file, the linker must fill in the 
correct addresses for such items as absolute addresses and references across sections. 
This is the process of relocation. 

Along with relocation, the linker performs resolution between modules, so that one module 
may reference symbols defined in a different module. At assembly time the module doing 
the referencing has no idea where the symbol it is referencing will be in the final absolute 
module. Therefore, the assembler sets up information in the relocatable object module 
which indicates that an external symbol is referenced in this module and where the symbol 
is referenced. In the relocatable object module where the symbol is defined there is infor¬ 
mation indicating that this is the module in which the symbol is defined, along with the val¬ 
ue of the symbol in the module. When the modules are presented as input to the linker, 
the correct value of the symbol can be inserted wherever it is referenced. 

If an external reference is made to a symbol for which there is no corresponding record in 
the input, the linker flags it as an unresolved external reference. No final values are as¬ 
signed to these references, and the resulting output file is unusable. A list of unresolved 
references is sent to the linker’s standard output and to the optional link map file. 

References in the input file may be specified as either absolute or relative expressions. 
An absolute expression is one which consists only of absolute terms, or is the difference 
between two relative terms. A relative expression consists of one relative term along with 
absolute terms and/or the result of two relative terms with opposing signs. Expressions 
in the input file are a modified notatipn as supported by the assembler. See Appendix E 
in the Motorola DSP Assembler Reference Manual for more information on the format 

of relocatable object file expressions. 
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1.4.2 Linker Passes 


The linker makes two partial passes over the input data. During the first pass, it collects 
section, symbol, and external reference information from each input file given on the com¬ 
mand line. If the input file is a library, the linker checks to see if there are any external 
references outstanding. If there are, the linker opens the library file and searches each 
module in the library until all external references are resolved or no more references can 
be satisfied within that library. If there are no outstanding unresolved references, the link¬ 
er skips the library. At the end of the first pass a list of unresolved external references is 
sent to the standard output as well as to the map file if one exists. References to unre¬ 
solved symbols may be fixed up using the SYMBOL directive of the memory control file, 
discussed below. 

Prior to the second pass, the linker scans its internal tables and performs fixups on section 
start addresses and symbol values. This includes setting the base relocation address for 
any memory spaces and counters as given by the -O option on the command line or the 
BASE directive in the memory control file. If a memory control file was specified on the 
command line it is opened and read to determine placement of any named sections in 
memory. 

Blocks of code and data are arranged in memory first by memory space then by location 
counter assignment. Absolute sections are located first, followed by ordered sections, 
and then any remaining sections are placed in memory. It is possible that addresses as¬ 
signed to a section using, for example, the low location counter might overlap addresses 
of another section using a different counter. This design is intentional so that counters 
may be used as a logical connection to the physical mapping of separate memories (e.g. 
internal and external RAM). 

During the second pass, the linker processes the data records, evaluating data fields as 
expressions and writing the modified values to the output file. Errors are reported during 
either pass, and the linker may abort depending on the severity of the error. Linker errors 
are routed to standard output so they may be redirected to a file if necessary. An output 
file produced with errors should not be used in any case. 

1.4.3 Linker Regions and Sections 

The basic relocatable entity is the section. A section ordinarily is created by the assem¬ 
bler SECTION directive. A section may contain code or data from any DSP memory 
space, and the addresses of the code or data may be relocatable or absolute. Sections 
that are not absolute at assembly time can be located either directly using the linker mem¬ 
ory control file SECTION directive, or indirectly via the linker command line >0 option or 
the control file BASE directive. Note that sections do not have to be relocatable to be 
linked; an absolute section can be lipked with any arbitrary module that contains or satis¬ 
fies a reference to that section. 

Sections may be grouped for relocation into regions. A region is a defined area of mem¬ 
ory where sections are located. Regions make it possible to specify varying base ad- 
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dresses for different groups of sections and set boundaries for section growth. Whereas 
sections represent blocks of code or data which are positioned within a given memory 
map, regions designate an area of a specified size where sections can be placed. 

There is always at least one default region. Other regions are defined using the linker RE* 
GION directive. A region always has a size and a start and end address, if these are not 
given, the linker uses default values (e.g. if no end address is supplied for a region, the 
highest target address is used). 

Regions should not overlap. The exception is the default region, which allows explicit re¬ 
gions to supercede it for relocation blocks. After all sections in explicit regions are located, 
the linker relocates remaining sections around the previously assigned blocks within the 
default region. This behavior can be altered with the linker RO option (see section 1.3). 


1.4.4 Memory Control File 

A memory control file optionally contains module identification, a global starting load ad¬ 
dress for linking purposes, and ordering, sizing, or placement information for any named 
sections. Section addresses may be for any memory space and any logical location 
counter (high, low, default). The memory control file also can specify physical memory 
mappings (internal, external) associated with any memory space or counter. In addition, 
global unresolved symbols may be assigned values in the memory control file. 

A memory control file is simply a text file containing linker directives. The directives are 
listed below: 

BASE REGION START 

IDENT RESERVE SYMBOL 

MAP SECSIZE 

MEMORY SECTION 


Several of the directives use the notation mem or memx to indicate the contents of a field. 
The definitions of mem and memx are as follows: 


mem 

<spo[<ctr>][<map>] :<exp> 


memx 

<spc>[<ctr>][<map>]:<exp>..<exp> 


spc 

X | 

Y | L | 

P 

ctr 

L | 

H 


map 

1 1 

E | R I 

A 

exp 

expression 





The spc field indicates one of the DSP memory spaces (X, Y, L, P). The ctr field specifies 
either Low or High location counters; if none is given the default counter is used. The map 

field indicates Internal memory, External memory, ROM, port A, or port B; this field may 

be omitted, in which case no explicit mapping is done. 
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1.4.4.1 BASE Directive 


BASE <mem>[,...,<mem>] 

The BASE directive indicates where to begin the location counter for the given memory 
region. This will be the base link address for all specified memory areas and all linked 
code and data within the region except for sections relocated absolutely via a memory file 
SECTION directive. Code and data not explicitly relocated will originate from this ad¬ 
dress. The BASE directive is analogous to the linker -0 command line option. 

Example: 



XE:$200,YE:$200,PI:$200 ; Set memory base addresses 


1.4.4.2 IDENT Directive 

IDENT <module name> <version> <revision> [;<comment>] 

The IDENT directive functions similarly to the assembler IDENT directive by identifying 
the name, version number, and revision number of the absolute or incrementally linked 
output module. The information is sent to the resulting output file. The cmodule name> 
adheres to the rules for assembly language labels, so that it must begin with an alphabetic 
character and consist only of alphanumeric characters or the underscore up to a length of 
255. The version number and revision number must be absolute expressions. If a com¬ 
ment follows the version and revision numbers it will be copied into the output file as well. 

Example: 

IDENT MYMODULE 1 2 ; MYMODULE, version 1, revision 2 

1.4.4.3 MAP Directive 

MAP <modifier> 

The MAP directive controls formatting of the link map (.MAP) file. There are currently two 
modifiers to the MAP directive, PAGE and OPT. 

1.4.4.3.1 MAP PAGE Modifier 

MAP PAGE <exp1>[,<exp2>[,<exp3>[,<exp4>[,<exp5>]]]] 

The MAP PAGE modifier works similarly to the assembler PAGE directive, and causes 
the .MAP file to be printed on the page according to the parameters supplied. If no MAP 
PAGE appears in the memory control file, the linker produces a map file with a column 
width of 80, a physical page length of 66 lines, and no blank lines at top and bottom. 

Example: 

MAP PAGE 132„3,3 
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The above MAP PAGE directive indicates a column width of 132, a physical page length 
of 66 lines (default), with three blank lines at the top and bottom of each page. 

1 A4.3.2 MAP OPT Modifier 


MAP OPT <option>[,<option>,...,<option>] 

The MAP OPT modifier determines the content of the output in the linker map file. The 
following MAP OPT options are available: 


NOCONST 

NOLOCAL 

NOSECADDR 

NOSECNAME 

NOSYMNAME 

NOSYMVAL 


- do not list symbols without a memory space attribute 

- do not list non*global symbols (e.g. symbols which 
are local to a section) 

- do not list sections by address 

• do not list sections by name 

• do not list symbols by name 

- do not list symbols by value 


If no MAP OPT is found in the memory control file, the linker will list all symbols and sec¬ 
tions by name, address, and value. 

Example: 


MAP OPT NOCONST, NOSYMVAL 


The above MAP OPT directive specifies no constants in the map listing and no symbols 
by value. 


1.4.4.4 MEMORY Directive 

MEMORY <mem>[,...,<mem>] 

The MEMORY directive establishes a maximum high memory address for locating code 
and data in the given memory region. If the linker attempts to relocate a block beyond the 
address specified in the MEMORY directive, an error will occur. This directive is useful 
for reflecting the true physical memory limits of the target system. 

Example: 

MEMORY PE:$1 FFF ; External program memory ends at hex 1FFF 
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1.4.4.5 REGION Directive 


REGION <region> [<mem>[,...,<mem>]] 


ENDR 

The REGION directive defines a region of memory in which to locate sections. The region 
name identifies the region. The optional <mem> parameter gives an absolute region size. 
The REGION directive is used in conjunction with existing control directives to specify a 
bounds for placing sections in memory. For example, a BASE directive used within a RE- 
GION/ENDR pair defines the base address for that region only. Likewise a MEMORY di¬ 
rective within a REGION scope indicates the high address for the enclosing region. 

Example: 

REGION 
BASE 
SECTION 

ENDR 

1.4.4.6 RESERVE Directive 

RESERVE <memx>[ <memx>] 

The RESERVE directive sets aside a block of memory which the linker will not use for re¬ 
location. The expression field in the <mem> parameter takes the form of a range n..m, 
where n is the low reserve address and m is the high reserve address. This directive can 
be used to protect ROM locations, system code, or uninitialized buffer areas. 

Example: 

RESERVE PI:$0..$1FF ; Protect interrupt vectors 

1.4.4.7 SECSIZE Directive 

SECSIZE <section> [<mem>[,...,<mem>]] 

The SECSIZE directive provides a mechanism for padding a section to a particular length 
despite its code or data content. The value field in the mem parameter is an expression 
which can either be an absolute size expressed as an integer, or a floating point value rep¬ 
resenting a percentage to pad. 

Example: 


INTERNAL_ROM X:$256,Y:$256 

X:0,Y:0 ; Base for INTERNAL_ROM region only 

BUFFERS 


SECSIZE PADSEC X:$1000,Y:$1000 ; X and Y absolute size 

SECSIZE PADSEC P:150.0 ; Increase size by one half 
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1.4.4.8 SECTION Directive 


SECTION <section> [<mem>[,...,<mem>]] 

The SECTION directive either assigns a section of code or data to an absolute location in 
DSP memory, or implies an ordering if no address specification is present. The addresses 
serve as the base for the corresponding memory spaces and counters in the named sec¬ 
tion. Any memory areas not indicated in the SECTION directive are relocated relative to 
the global starting load address given by the -O command line option or the memory file 
BASE directive. If there is no -O option or BASE directive, unassigned areas are placed 
in memory relative to location zero. 

If the SECTION directive appears with only a section name and no address, it means that 
the linker should locate this section in memory before handling any other default sections. 
Thus given a set of sections A, B, C, and D, if B and C were listed in SECTION directives 
without a corresponding address, the linker would place B and C in memory before A and 
D. This provides a means for ordering sections in memory. 

Example: 

SECTION ABS X:$2000,Y:$2000 ; X and Y absolute base 

SECTION ORD ; Ordered section 

1.4.4.9 START Directive 

START <expression> 

The START directive gives an alternative start address to which the program will jump at 
runtime. This value is ordinarily given by the assembler END directive. The expression 
may consist of an absolute value or a symbol whose value will be adjusted during link pro¬ 
cessing. 

Example: 

START BEGIN ; Jump to location BEGIN after loading 

1.4.4.10 SYMBOL Directive 

SYMBOL <symbol> { <mem> | <expression>} 

The SYMBOL directive allows the programmer to specify a value for an otherwise unre¬ 
solved reference. The named symbol must not have been defined during link processing. 
The symbol is stored as an absolute global symbol. The symbol value may be either in¬ 
teger or floating point. If the value is an address it may contain a memory space reference 
and optionally a counter and mapping designation. 

Example: 

SYMBOL TARGET X:$200 ; Set TARGET to hex 200 
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1.4.4.11 Memory Control File Example 

Figure 1 shows the contents of an example memory control file. The IDENT directive 
identifies the object module and gives it explicit version and revision numbers. The com¬ 
ment is also preserved in the output file. The START directive gives a starting address of 
FILTER for the program, overriding any previous settings done with the assembler END 
directive. 

The BASE directive indicates that the X and Y low memory counters are to be mapped 
into internal DSP memory, with a starting address of 100 hexadecimal. Any data associ¬ 
ated with the X or Y low memory counters, and not relocated due to a subsequent memory 
file SECTION directive, will be assigned addresses relative to this starting location. The 
BASE directive also shows that X and Y high memory counters have been assigned start¬ 
ing address 2000 hexadecimal in external DSP memory, and that linking to external pro¬ 
gram memory begins at location 200 hexadecimal. Note that any memory specifications 
given by the -O command line option override the values supplied by the memory file 
BASE directive for the default region. 

The RESERVE directives set aside a part of the low internal X and Y data memory, even 
though the base address is lower than the reserved area. The linker will locate data 
around the reserved portions as if they had been previously allocated. 

The REGION directive defines a sized region of memory for modulo buffers in internal 
ROM. The corresponding MEMORY directive indicates that there are only 256 words of 
memory in each data space for this region (the default base is zero). 

The example SECTION directives are similar to the format of the BASE directive, except 
that the particular section is named so that the individual section counters may be modi¬ 
fied. For the section named INPUT, the program low memory counter is initialized to 100 
hex and mapped to external memory. The program memory for the FILTER section uses 
the default location counter and sets the initial value to 400 hex, mapped to external mem¬ 
ory. Finally, the OUTPUT section is set to 800 hex, using the high memory P space 
counter mapped to external memory. 

Two unresolved symbols are given values with the SYMBOL directive. The symbol XDA- 
TA is assigned to external high X memory with a value of 2000 hexadecimal. The symbol 
YDATA is assigned to external high Y memory with a value of 2000 hexadecimal. Both 
symbols will be stored as absolute global entities. 

The MAP directives control the formatting and content of the link map file. The first direc¬ 
tive sets the page width to 132, with three blank lines at top and bottom. The second di¬ 
rective disables the reporting of sections by address and symbols by value. 
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ident filter 2 1 ; Filter module 

start filter 

base xli:$100,xhe:$2000,yli:$100,yhe:$2000,pe:$200 

rese rve xl i :$200.. $3ff, y I i :$200. .$3ff 

region intemal_rom 

memory x:256,y:256 

section buffers 

endr 

section input ple:$100 

section filter pe:$400 

section output phe:$800 

symbol xdata xhe:$2000 

symbol ydata yhe:$2000 

map page 132„3,3 

map opt nosecaddr.nosymval 

Figure 1. DSP Linker Memory Control File Example 
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Chapter 2 

MOTOROLA DSP LIBRARIAN 


2.1 INTRODUCTION 

The Motorola DSP Librarian is a stand-alone utility that allows separate files to be grouped 
together into a single file for linking or archival storage. After a library is created, files may 
be added, deleted, replaced, or extracted from the library. The library contents may also 
be listed, indicating the module name (base name of the input file path), size in bytes, and 
the date and time the module was entered into the library. 

2.2 INSTALLING THE LIBRARIAN 

The librarian is distributed on various media and in different formats depending on the 
host operating system environment. See Appendix G in the Motorola DSP Assembler 
Reference Manual, HOST-DEPENDENT INFORMATION, for details on installing and 
operating the librarian on your particular machine. 

2.3 RUNNING THE LIBRARIAN 

The general format of the command line to invoke the librarian is: 

DSPLIB [options] [<library>] [<files>] 

where: 

[options] 


Any one of the following command line options. The single option must pre¬ 
cede the library name. Option letters may be specified in either upper or 
lower case. If no option is supplied, the librarian operates as if the update 
(-U) option were given. 
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-A 


This option adds the modules in the file list to the named library. The library 
file must exist, and the modules must not already be in the library. 

Example: DSPLIB -A fftlib fft16.cln fft512.cln ditfft.cln 

In this example, the files FFT16.CLN, FFT512.CLN, and 
DITFFT.CLN are added to the existing library FFTLIB.LIB. 



Create a new library file and add any specified modules to it. If the library 
file already exists, an error is issued. 

Example: DSPLIB -C fftlib fft16.cln fft512.cln ditfft.cln 

In this example, a new library file FFTLIB.LIB is created and the files 
FFT16.CLN, FFT512.CLN, and DITFFT.CLN are added to the li¬ 
brary. 



Delete the named modules from the library. If the module is not in the li¬ 
brary, an error is issued. 

Example: DSPUB-D fftlib fft16.cln 

In this example, the module FFT16.CLN is removed from the library 
FFTLIB.LIB. 


-F<argfil> 


Indicates that the librarian should read command line input from <argfil>. 
<argfil> can be any legal operating system filename, including an optional 
pathname. <argfil> is a text file containing module names to be passed to 
the librarian. The arguments in the file need be separated only by some 
form of white space (blank, tab, newline). A semicolon (;) on a line following 
white space makes the rest of the line a comment. 

The -F option was introduced to circumvent the problem of limited line 
lengths in some host system command interpreters. 

Example: DSPLIB -Fopts.cmd 

Invoke the librarian and take command line filenames from the com¬ 
mand file OPTS.CMD. 
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-L 


List library contents. This option lists the module name as contained in the 
library header, the module size (less library overhead), and the date and 
time the file was stored into the library. The listing output is routed to stan¬ 
dard output so that it may be redirected to a file if desired. 

Example: DSPUB -L fftlib > fftlib.lst 

This example lists the contents of the library FFTLIB.LIB. The output 
is redirected to the file FFTLIB.LST. 



This option replaces the named modules in the given library. The modules 
must already be present in the library file. 

Example: DSPLIB -R fftlib fft512.cln ditfft.cln 

This example replaces the files FFT512.CLN and DITFFT.CLN in the 
library FFTLIB.LIB. 



This option updates the specified modules if they exist in the library; other¬ 
wise it adds them to the end of the library file. 

Example: DSPUB -U fftlib ditfft.cln 

In this example, the file DITFFT.CLN is updated in the library 
FFTLIB.LIB. 



Display the librarian version number and copyright notice on standard out¬ 
put. 

Example: DSPLIB -V 

This example displays the current librarian version number and copy¬ 
right notice. 



Extract named modules from the library. The resulting files are given the 
name of the modules as stored in the library module header. 

Example: DSPLIB fftlib fft16.cln fft612.cln 

This example extracts the files FFT16.CLN and FFT512.CLN from 
the library FFTLIB.LIB. The files are placed in the current directory. 
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<library> 


An operating system compatible filename (including optional pathname) 
specifying the library file to create or access. If no extension is supplied, the 
librarian will automatically append .LIB to the filename. If no pathname is 
specified, the librarian will look for the library in the current directory. 

The librarian also has an interactive mode, where commands can be en¬ 
tered repeatedly without reloading the librarian program for each operation. 
If the librarian is invoked without arguments, it prompts for a command 
string. The interactive commands correspond to those given above, and the 
syntax is similar to that of the command line. Because interactive input is 
taken from the standard input channel of the host environment, it is possible 
to create a batch of librarian commands and feed them to the program for 
execution via redirection. Enter help or ? at the prompt for more information 
on the librarian interactive mode. 


<files> 

A list of operating system compatible filenames separated by blanks. If no 
pathname is specified for a given file, the librarian will look for that file in the 
current directory. For input operations the filenames may also contain an 
optional pathname; the path is stripped when the file is written to the library. 
For output operations only the filename should be used to refer to library 
modules. The list of files will be processed sequentially in the order given. 

2.4 LIBRARY PROCESSING 

A library file may contain several relocatable object modules, each of which contains one 
or more global symbol definitions. Rather than being normal input to the linker, a library 
file is searched. This means that for each relocatable object module in the library, a check 
is made to determine whether any globally defined symbols in the library module match 
any externally referenced symbols encountered in previous input modules. If so, the re¬ 
locatable object module from the library is included in the executable file. If not, the search 
continues with the next module in the library file. 
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Chapter 3 

MOTOROLA DSP S-RECORD CONVERSION UTILITY (SREC) 


3.1 INTRODUCTION 

The Motorola DSP S-Record Conversion Utility SREC converts Motorola DSP COFF for¬ 
mat files into Motorola S-record files. The S-record format was devised for the purpose 
of encoding programs or data files in a printable form for transportation between computer 
systems. Motorola S-record format is recognized by many PROM programming systems. 

3.2 INSTALLING SREC 

SREC is distributed on various media and in different formats depending on the host op¬ 
erating system environment. See Appendix G in the Motorola DSP Assembler Refer¬ 
ence Manual, HOST-DEPENDENT INFORMATION, for details on installing and 
operating SREC on your particular machine. 

3.3 RUNNING SREC 

The general format of the command line to invoke SREC is: 

SREC [options] <files> 

where: 

[options] 

Any of the following command line options. The options must precede the 
file names. Option letters may be specified in either upper or lower case. 

•B 


Use byte addressing when transferring load addresses to S-record address¬ 
es. This means that object file start addresses are multiplied by the number 
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of bytes per target DSP word and subsequent S1/S3 record addresses are 
computed based on the data byte count. 

Example: SREC -B prog 

In this example, the file PROG.CLD is translated to S-record format 
using byte addressing. The load addresses will be multiplied by the 
number of bytes per DSP word. A separate output file will be pro¬ 
duced for each DSP memory space (X, Y, L, or P) represented in the 
input file. 


-L 

Use double-word addressing when transferring load addresses from L 
space to S-record addresses. This means that object file records for L 
space data are moved unchanged and subsequent S1/S3 record addresses 
are computed based on the data word count divided by 2. This option 
should always be used when the object file contains sections in L memory 
space. 

Example: SREC-L filter.cld 

Convert the file FILTER.CLD into separate S-record files for each 
memory space in the object file. Convert L space load addresses to 
long addresses in the S-record file. 


Split each DSP word into bytes and store the bytes in parallel S-records. 
The -M and -S options are mutually exclusive. 

Example: SREC -M main 

For each memory space in the file MAIN.CLD create multiple S- 
record files that correspond to each byte in the target DSP word. For 
example, if MAIN.CLD contained only references to P memory and 
the target DSP is the DSP56000, then SREC would produce the files 
MAIN.PO, MAIN.P1, and MAIN.P2. 

-P<procno> 

Assume <procno> object file format. This makes a difference in the type of 
S-type data records produced. <procno> is one of the Motorola DSP pro¬ 
cessor numbers, e.g. 56000, 96000, etc. This option overrides the object 
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file machine ID. It is useful for handling object files from programs that do 
not generate target machine information. 

Example: SREC -P56000 prog 

The file PROG.CLD is translated to S-record format with the assump¬ 
tion that the target processor is in the DSP56000 family of proces¬ 
sors. 



Write bytes high to low, rather than low to high. This option has no effect 
when used with the -M option. 

Example: SREC -R prog 

The file PROG.CLD is translated to S-record format with bytes writ¬ 
ten high to low. A separate output file will be produced for each DSP 
memory space (X, Y, L, or P) represented in the input file. 



Write data to a single file, putting memory space information into the ad¬ 
dress field of the SO header record. The -M and -S options are mutually ex¬ 
clusive. 

Example: SREC -S filter 

This example writes the S-record output to a single file called FIL- 
TER.S and stores the memory space information in the address field 
of the SO header record. An SO record is emitted whenever the mem¬ 
ory space changes in the object file. 



Use word addressing when transferring load addresses to S-record ad¬ 
dresses. This means that object file start addresses are moved unchanged 
and subsequent SI /S3 record addresses are computed based on the data 
word count. 

Example: SREC -W main 

In this example, the file MAIN.CLD is translated to S-record format 
using word addressing. A separate output file will be produced for 
each DSP memory space (X, Y, L, or P) represented in the input file. 

<files> 


A list of operating system compatible filenames separated by blanks. If no 
pathname is specified for a given file, SREC will look for that file in the cur¬ 
rent directory. If the special character is used as a filename SREC will 
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read from the standard input stream. The list of files will be processed se¬ 
quentially in the order given. 

3.4 SREC PROCESSING 

SREC takes as input a Motorola DSP absolute object file and produces byte-wide Motor¬ 
ola S-record files suitable for PROM burning. The Motorola DSP COFF file header 
records are mapped into SO and S7/S9 records respectively. DSP COFF section raw data 
is mapped into SI or S3-type records depending on the source processor. 

Since Motorola DSPs use different word sizes, the words must be split into bytes and 
stored in an appropriate format. The program examines the machine type field in the ob¬ 
ject file optional header to determine the appropriate S-record format to use. For exam¬ 
ple, if the machine ID in the object file header record is DSP56000, SREC generates Si/ 

S9 output records; if the machine ID is DSP96000, the program generates S3/S7 records. 

In the default mode of operation the program writes the low, middle, and high bytes of 
each word consecutively to the current S1/S3 record being written. For example, given 
the DSP56000 raw data record below: 

0008F8 300000 340000 094E3E 

I 

fourth word 
third word 
second word 
first word 

SREC would create the following SI record: 

byte count field 

address field checksum field 

I I 

S10D0000F808000000300000343E4E09F9 

! u _ 

fourth word 
third word 
second word 
irst word 

Output records are written to a file named according to the following convention: 

<basename>.<M> 

where <basename> is the filename of the input object file without extension and <M > is 
the memory space specifier (X, Y, L, or P) for this set of data words. Note that a separate 
file is created for each memory space encountered in the input file; thus the maximum 
number of output files in the default mode is 4. 
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When the -M option is specified, SREC splits each DSP source word into bytes and stores 
the bytes in parallel S1/S3 records. For example, the following DSP56000 raw data: 

0008F8 300000 340000 094E3E 

I 

fourth word 
third word 
second word 
first word 

would be converted by SREC into the three SI records below: 

byte count field 
address field 

SI 070000F800003EC2 -- low byte 
SI 0700000800004EA2 - mid byte 

SI 070000003034098B - high byte 

I 

checksum field 
fourth word 
third word 
second word 
first word 

The three records corresponding to the high, middle, and low bytes of each data word are 
written to separate files. The files are named according to the following convention: 

<basename>.<M><#> 

where <basename> is the filename of the input object file without extension, <M> is the 
memory space specifier (X, Y, L, or P) for this set of data words, and <#> is one of the 
digits 0,1, or 2 corresponding to low, middle, and high bytes, respectively. 

Note that a separate set of byte-wide files is created for each memory space encountered 
in the input file. Thus the number of output files generated is (number of memory spaces 

in input * size of DSP word). 

The -S option writes all information to a single file, storing the memory space information 
in the address field of the SO header record. The values stored in the address field and 
their correspondence to the DSP memory spaces are as follows: 

Value 
1 
2 

3 

4 

When the memory space changes in the object file section record, a new SO header 
record is generated. The resulting output file is named <basename>.S, where <base- 





MOTOROLA DSP LINKER/LIBRARIAN REFERENCE MANUAL 






name> is the filename of the input object file without extension. The -M and -S options are 
mutually exclusive. 

Address fields in DSP section records are copied as is to the appropriate SI or S3 record. 
Subsequent SI or S3 record addresses are byte incremented until a new section is en¬ 
countered or end-of-file is reached. In some cases the starting S1/S3 record address 
must be adjusted for byte addressing by multiplying the section start address by the num¬ 
ber of bytes in a DSP word. When the -B option is given, any section address fields are 
adjusted to begin on a byte-multiple address. If the -W option is specified (the default) 
byte-incrementing is not done when generating S-record addresses, e.g. the S-record ad¬ 
dresses are word-oriented rather than byte-oriented. The -B and -W options have no ef¬ 
fect when used in conjunction with the -M mode, since in that case byte and word address 
mappings are 1:1. 

Section records for L space memory contain words which are loaded into adjacent X and 
Y memory locations. In these cases performing the default strict word addressing may be 
inappropriate. The -L option may be given to indicate that double-word addressing should 
be used to generate subsequent S1/S3 addresses after the initial load address. In addi¬ 
tion the -L option should be used when doing byte addressing since the initial load ad¬ 
dresses must be adjusted to account for double-word addressing in the object file. In 
general, it is a good idea to use the -L option whenever the input object file contains sec¬ 
tions which refer to L memory space. 

3.5 S-RECORD FILE FORMAT 

An S-record file consists of a sequence of specially formatted ASCII character strings. 
These character strings are made up of several fields which identify the record type, 
record length, memory address, code or data, and checksum. Each byte of binary data 
is encoded as a 2-character hexadecimal number, the first character representing the 
high-order 4 bits, and the second the low-order 4 bits of the byte. 

3.5.1 S-Record Content 

An S-record consists of 5 distinct fields: the TYPE field, the RECORD LENGTH, AD¬ 
DRESS field, CODE/DATA, and the CHECKSUM field. 
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Field 

Type 

Record length 


Printable 


Address 

Code/data 


Checksum 



4, 6, or 8 
0-2 n 




S-record type: SO, SI, etc. 

The count of the character pairs in the 
record, excluding the type and record 
length. 

The 2-, 3-, or 4-byte address at which the 
data field is to be loaded into memory. 

From 0 to n bytes of executable code, 
memory loadable data, or descriptive in¬ 
formation. 

The least significant byte of the one’s 

complement of the sum of the values rep¬ 
resented by the pairs of characters mak¬ 
ing up the record length, address, and 
the code/data fields. 


3.5.2 S-Record Types 

There are ten possible Motorola S-record types. The following sections discuss the S- 
record types used by the Motorola DSP SREC utility. 


3.5.2.1 SO Record 

The SO record is the header record (sometimes called the ‘sign-on’ record) for a block of 
Motorola S-records. The address field is always 4 printable characters representing a 2- 
byte address. It is normally zero, but when the SREC -S option is used, the program gen¬ 
erates a code corresponding to the DSP memory space of the subsequent S-record data 
block: 


Value 
1 
2 

3 

4 

With the -S option whenever a memory change occurs a new SO header record is pro¬ 
duced. In this case if a data block were to be located in X memory, the address field would 
contain ‘30303031 ’ (note that such use of the SO address field is a DSP-specific extension 
to the standard SO record format). The code/data field may contain any descriptive infor¬ 
mation identifying the following block of S-records. This is followed by the normal two- 
characte r checksu m. 
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3.S.2.2 SI, S2, S3 Records 


Each data record begins with the start characters SI, S2, or S3 followed by a byte count. 
These record types vary only by the length of their respective address fields. An SI record 
has a 2-byte address field represented by 4 hexadecimal characters. An S2 record has 
a 3-byte address field represented by 6 hexadecimal characters. An S3 record has a 4- 
byte address field represented by 8 hexadecimal characters. The SREC program current¬ 
ly uses only SI-type records for DSPs with 2-byte addresses (DSP56000, DSP56100) 
and S3-type records for DSPs with 4-byte addresses (DSP96000). Data bytes follow the 
address field and are represented by hexadecimal character pairs. A two-character 
checksum terminates the data record. The SREC program guarantees that the number 
of bytes in an SI or S3 data record is an integral multiple of the word size of the target 
DSP. 

3.5.2.3 S7, S8, S9 Records 

These are end-of-file records and may appear only once in the S-record file. Each trailer 
record begins with the start characters S7, S8, or S9 followed by a byte count. As with 
the data records these record types vary only by the length of their respective address 
fields. An S7 record has a 4-byte address field represented by 8 hexadecimal characters. 
An S8 record has a 3-byte address field represented by 6 hexadecimal characters. An S9 
record has a 2-byte address field represented by 4 hexadecimal characters. The SREC 
program currently uses only S9-type records for DSPs with 2-byte addresses (DSP56000, 
DSP56100) and S7-type records for DSPs with 4-byte addresses (DSP96000). The ad¬ 
dress field in the trailer record is used by the SREC program to store the end address giv¬ 
en in the object file optional header record. A two-character checksum immediately 
follows the address field. 
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Chapter 4 

MOTOROLA DSP COFF FILE DUMP UTILITY (COFDMP) 


4.1 INTRODUCTION 

The Motorola DSP COFF file dump program COFDMP is a stand-alone utility that reads 
an absolute or relocatable Common Object File Format (COFF) file and produces a for¬ 
matted display of the object file contents. The entire file or only selected portions may be 
processed depending on command line options. The program also can generate either 
codes or symbolic references to entities such as symbol type and storage class. 

4.2 INSTALLING COFDMP 

The COFDMP program is distributed on various media and in different formats depending 
on the host operating system environment. See Appendix G in the Motorola DSP As¬ 
sembler Reference Manual, HOST-DEPENDENT INFORMATION, for details on install¬ 
ing and operating COFDMP on your particular machine. 

4.3 RUNNING COFDMP 

The general format of the command line to invoke COFDMP is: 

COFDMP [options] <files> 


where: 

[options] 


Any of the following command line options. The options must precede the 
file name. Option letters may be specified in either upper or lower case. If 
no option is supplied the entire input file is dumped. 
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-c 



UTILITY tCOFDMPl 


Dump the string table of the specified file. This information may not be 
present if the object file has been stripped. 

Example: COFDMP -C fft16.cld 

In this example, the symbol table is listed from the absolute object file 
FFT16.CLD. 


-D<dmpfil> 


This option specifies that a dump file is to be created for cofdmp output. 
<dmpfil> can be any legal operating system filename, including an optional 

pathname. 

If the -D option is not specified, then the program will route dump output to 
the standard output (usually the console or terminal screen) by default. The 
-D option should be specified only once. If the file named in the -D option 
already exists, it will be overwritten. 

Example: COFDMP -D filter.dmp filter.cld 

In this example, the absolute load file FILTER.CLD will be dumped to 
the output file FILTER.DMP. 




Dump the file header of the specified file. 

Example: COFDMP -F fft16.cln 

In this example, the file header is listed from the relocatable object 
file FFT16.CLN. 


Dump the section headers of the specified file. 

Example: COFDMP -H fft16.cld 

In this example, the section headers are listed from the absolute ob¬ 
ject file FFT16.CLD. 
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Dump the source file line number information from the specified file. This 
information may not be present if the object file has been stripped. 

Example: COFDMP -L fft16.cln 

In this example, the source file line number information is listed from 
the relocatable object file FFT16.CLN. 


Dump the optional header of the specified file. 

Example: COFDMP >0 fft16.cln 

In this example, the optional header is listed from the relocatable ob¬ 
ject file FFT16.CLN. 


Dump section relocation entries from the specified file. Only relocatable ob¬ 
ject files will contain this information. 

Example: COFDMP -R fftl 6.cln 

In this example, the section relocation information is listed from the 
relocatable object file FFT16.CLN. 


Dump the section raw data from the specified file. 

Example: COFDMP -S fft16.cld 

In this example, the section raw data is listed from the absolute object 
file FFT16.CLD. 


Dump the symbol table from the specified file. This information may not be 
present if the object file has been stripped. 

Example: COFDMP -T fft16.cln 

In this example, the symbol table is listed from the relocatable object 
file FFT16.CLN. 
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Dump the specified file symbolically, using names for bit flags, symbol 
types, and storage classes. 

Example: COFDMP -V fft16.cld 

in this example, the entire contents of the absolute object file 
FFT16.CLD is dumped symbolically. 

<files> 

A list of operating system compatible filenames. If no pathname is specified 
for a file, the program will look for that file in the current directory. An explicit 

filename must be provided; there is no default extension for the input file. 

4.4 COFDMP PROCESSING 

The COFDMP program reads the input file and writes a formatted dump of the file con¬ 
tents to the standard output (unless the -D command line option is given). I/O redirection 
may be used to send the output to a file if the host operating system supports it. 

The program currently will not dump individual modules from library files; they must be ex¬ 
tracted and then dumped. Also note that if the file has been stripped some information 
may no longer be available in the file, such as relocation information, line number entries, 
and symbol and string table data. 

The input file must be a Motorola DSP COFF object file, either absolute or relocatable. 
See Appendix E in the Motorola DSP Assembler Reference Manual, MOTOROLA DSP 
OBJECT FILE FORMAT, for more information on Motorola DSP COFF object files. 
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Appendix A 
LINKER MESSAGES 


A.1 INTRODUCTION 

Linker messages are grouped into four categories: 

Command Line Errors 

These errors indicate invalid command line options, missing filenames, file open 
errors, or other invocation errors. Command line errors generally cause the linker 
to stop processing. 

Warnings 

Warnings notify the programmer of suspect constructs but do not otherwise affect 
the object file output. 

Errors 


These errors indicate problems with object file format, size of address fields, and 
syntax. In these cases the resulting object code is generally not valid. 




Fatal errors signify serious problems encountered during the link process such as 
lack of memory, file not found, or other internal errors. The linker halts immediate¬ 
ly. 

The linker also will provide information on the file name, module ID, and section location 
of the error, if it can be ascertained. Messages are always routed to standard output. 
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A.2 COMMAND LINE ERRORS 


Cannot open command file 
Cannot open map file 
Cannot open object file 
Cannot open memory control file 

The file associated with a -B, -F, -M, or -R command line option was not found or 
could not be opened. 

Cannot open library file 
Cannot open source file 

The input file or library was not found or could not be opened. 

Default object file not allowed in incremental link 

When performing an incremental link using the -I option the -B option must be used 
in order to name the output object file. The default naming convention cannot be 
used because it might overwrite one of the input files. 

Duplicate map file specified - ignored 
Duplicate memory control file specified - ignored 
Duplicate object file specified - ignored 

More than one -B, -M, or -R option was encountered on the command line. 

Illegal command line option 

The option specified on the command line was not recognized by the linker. 

Illegal memory map character 

The memory map indicator must be I for internal memory, E for external memory, 
R for ROM, A for port A, B for port B, or absent for no explicit mapping. 

Illegal memory space specified 

The memory space specifier must indicate one of the DSP memory spaces (X.Y.L, 
or P). 

Missing command line option argument 

The expected arguments following a command line specifier were missing. 

Missing link filename 

There must be at least one link filename specified on the command line. 

No modules linked - empty object file 

An object file header record was never found in the input. 
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ROM mapping not available in L memory 

The ROM mapping indicator in a -O command line option is not valid when locating 
data in L memory space. 

Source file name same as map file name 
Source file name same as object file name 

One of the source files appeared to the linker to have the same name as the spec¬ 
ified map or object file. The linker aborts rather than potentially writing over a link 
input file. 

Syntax error in command line 

The syntax for the command line -O origin option is not correct (possibly missing a 
colon before the address specification). 
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A.3 WARNINGS 
Duplicate global symbol 

A global symbol in one link file was also defined by the same name in a different 
module. 

Duplicate XDEF symbol 

An external symbol in one link file was also defined by the same name in a different 
module. 

Empty bit mask field 

The first operand of a BFxxx-type instruction was zero. 

Expression value outside fractional domain 

The expected fractional value was not within the range -1.0 <= m < 1. 

File contains no line number information 

The -G command line option was given to preserve debug information but there is 
no line number information in the input file. 

Load location counter overflow 
Load location counter underflow 

The load location counter exceeded its maximum or minimum value. The linker 
wraps the counter value around and continues. 

No modules linked - empty object file 

An object file header record was never found in the input. 

Options for both debug and strip specified - strip ignored 

Both the -G and -Z options were given on the command line. The -G option takes 
precedence. 

Runtime location counter overflow 
Runtime location counter underflow 

The runtime location counter exceeded its maximum or minimum value. The linker 
wraps the counter value around and continues. 

Section already set as absolute 

A section listed as ordered in a memory control file SECTION record was found to 
be already located absolutely. 
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String truncated in expression evaluation 

Only the first four characters of a string constant are used during expression eval¬ 
uation. 

Strip not valid with incremental link - ignored 

The -I and -Z command line options are mutually exclusive. The -I option takes 
precedence. 
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A.4 ERRORS 
Arithmetic exception 

An internal floating point exception occurred while evaluating an expression. The 
result of the evaluation is probably not valid. 

Binary constant expected 

A character other than ASCII 'O’ or'T either followed the binary constant delimiter 
(%) or appeared in an expression where a binary value was expected by default. 

Bit mask cannot span more than eight bits 

If the first operand of a BFxxx-type instruction was shifted one bit to the right until 
the low-order bit was a 1, the resulting value must not exceed $FF hexadecimal. 

Buffer block too large 

The runtime location counter overflowed while the linker was attempting to allocate 
storage for a data buffer. The linker automatically advances the program counter 
to the next valid base address given the size of the modulo or reverse carry buffer. 

Buffer out of order 

The buffer sequence numbers in the input stream are out of phase. 

Decimal constant expected 

A character other than ASCII ’O' through '9' either followed the decimal constant de¬ 
limiter (') or appeared in an expression where a decimal value was expected by 
default. 

Divide by zero 

The expression evaluator detected a divide by zero. 

Duplicate global symbol 

Two identically named global symbols have been found. 

Duplicate local symbol 

Two identically named symbols have been found which are local to the same sec¬ 
tion. 

Duplicate special symbol 

t 

The linker reserves a few symbol names to deal with certain floating point entities 
such as Infinity and Not-a-Number. These symbols are Inf, Nan, Tiny, and Huge. 
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Expression cannot have a negative value 

The MAP PAGE directive does not allow negative expression arguments. 

Expression involves incompatible memory spaces 

The memory space attribute is regarded by the linker as a type, in the same sense 
that high level languages use type for variables. Symbols may have memory 
space attributes of X, Y, L, P(rogram), or N(one); only N is fully compatible with all 
other attributes. In this case, two operands were evaluated with different memory 
space attributes, neither of which was N. 

Expression result must be absolute 

Certain directives and some linker usage require absolute values as arguments or 
operands. 

Expression result must be integer 

The expression refers to an address; therefore the result must be an integer within 
the address range of the target DSP. 

Extra characters beyond expression 

The expression evaluator found extra characters after the end of a valid expres¬ 
sion. Unbalanced parentheses can cause this error. 

Extra characters in function argument or missing ')' for function 

Mismatched parentheses or wrong number of parameters in a function invocation. 

Floating point constant expected 

A character other than ASCII 'O' through '9', 'e' or 'E', or'.’ appeared in an expres¬ 
sion where a floating point value was expected by default. 

Floating point not allowed in relative expression 

Relative expressions are generally used for address computation, therefore a float¬ 
ing point value would not be appropriate. 

Hex constant expected 

A character other than ASCII 'O' through '9', 'a' through T, or 'A' through 'F either 
followed the hexadecimal constant delimiter ($) or appeared in an expression 
where a hexadecimal value was expected by default. 

Illegal memory counter specified' 

The memory counter specifier must be H forthe high counter, L forthe low counter, 
or absent for the default counter. 
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Illegal memory map character 

The memory map Indicator must be I for internal memory, E for external memory, 
R for ROM, A for port A, B for port B, or absent for no explicit mapping. 

Illegal memory space specified 

The memory space specifier must indicate one of the DSP memory spaces (X,Y,L, 
or P). 

Illegal operator for floating point element 

Bitwise operators are invalid for floating point values. 

Invalid address expression 

The memory space attributes of the expression operands are incompatible. 

Invalid address relocation field 

Either a new record began or end-of-file was reached when the linker was reading 
the address specification in a memory file BASE or SECTION record. 

Invalid function name 

The linker could not match an internal function name. 

Invalid global section 

A section with a sequence number of zero did not have the proper global section 
name. 

Invalid MAP option 
Invalid MAP option field 
Invalid MAP page field 
Invalid MAP record field 

One of the options or fields in a memory control file MAP record was not recog¬ 
nized by the linker. 

Invalid overlay base address 

An overlay base address was given that specified an address within another over¬ 
lay segment. 

Invalid page length specified 

The minimum page length allowed by the MAP PAGE directive is 10 lines per 
page. The maximum is 255. 
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Invalid page width specified 

The minimum page width allowed by the MAP PAGE directive is 1 column per line. 
The maximum is 255. 

Invalid relative expression 

The terms of a relative expression may only participate in addition and subtraction 
operations and must have opposing signs. 

Invalid relocation type field 

An invalid record type was encountered in the memory control file. 

Invalid reserve range syntax 

The syntax for the memory control file RESERVE is such that the range is given as 
two values from the same memory space and mapping, separated by two periods 
in succession (..). 

Invalid revision number field 

The revision number field in a memory control file I DENT record is not valid. The 
value must be a decimal integer number. 

Invalid section number 

A new section encountered by the linker does not have a unique section number. 

Invalid shift amount 

A shift expression must evaluate to within the range 0 <= n <- 32. 

Invalid start address expression 

The end address expression in the optional header record is malformed. 

Invalid start address field 

The start address field in a memory control file START record is not valid. The con¬ 
tents must be a positive numeric value. 

Invalid symbol 

Symbols are limited to 255 characters. The first character must be alphabetic or 
the underscore character (A-Z, a-z, _). The remaining characters must be alpha¬ 
numeric, including the underscore character (A-Z, a-z, 0-9, _). 

« 

Invalid symbol memory mapping 

The memory type for a symbol in the symbol table does match a valid linker mem¬ 
ory configuration. 
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Invalid symbol name field 

Either a new record began or end-of-file was reached when the linker was reading 
the name specification in a memory file SYMBOL record. 

Invalid symbol value field 

Either a new record began or end-of-file was reached when the linker was reading 
the value specification in a memory file SYMBOL record. 

Invalid version number field 

The version number field in a memory control file IDENT record is not valid. The 
value must be a decimal integer number. 

Left margin exceeds page width 

The blank left margin value in the MAP PAGE directive exceeds the default or 
specified page width parameter. 

Missing'(’ for function 

Parentheses are not balanced in an internal function call. 

Missing')' In expression 

Parentheses are not balanced in an expression. 

Missing *]' in expression 

Square brackets are not balanced in an expression. 

Missing in expression 

Curly braces are not balanced in an expression. 

Missing expression 

An expression was expected by the expression evaluator. 

Missing quote in string 

A single or double quote character was expected by the string parsing routines. 
Missing string after concatenation operator 

The string concatenation operator (++) must be followed by another quoted string. 
No previous function declaration' 

An end-of-function symbol record was encountered without a corresponding func¬ 
tion type symbol record. 
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Operation not allowed with address term 

Only addition and subtraction are allowed in expressions with address terms. 

Operation not allowed with relative term 

Only addition and subtraction are allowed in expressions with relative terms. This 
error may be disabled with the linker AEC option. 

Overlay address involves incompatible memory spaces 

The memory space attribute is regarded by the linker as a type, in the same sense 
that high level languages use type for variables. Symbols may have memory space 
attributes of X, Y, L, P(rogram), or N(one); only N is fully compatible with all other 
attributes. In this case, the runtime overlay address was found to be incompatible 
with the memory space used as the overlay origin. 

Overlay out of order 

The overlay sequence numbers in the input stream are out of phase. 

Page length too small for specified top and bottom margins 

The sum of the top and bottom margins specified in the MAP PAGE directive is 
greater than the page length -10. 

Page length too small to allow default bottom margin 

The bottom margin exceeds the page length specified in the MAP PAGE directive. 

Relative expression must be integer 

A relative expression must evaluate to an integer value. 

Relative terms from different sections not allowed 

Two relative terms from different sections may not participate in an arithmetic op¬ 
eration since the result might not be meaningful. This error may be disabled with 
the linker XC option. 

ROM mapping not available in L memory 

The ROM mapping indicator in a memory control file record is not valid when locat¬ 
ing data in L memory space. 

Section out of order 

The section number of the current section did not match the section count. 
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Section padding percentage too small 


The percentage of padding in a memory control file SECSIZE record must be 
greater than 100.0. 

Symbol already defined 

A symbol assumed to be unresolved and named in a memory file SYMBOL record 
has already been defined. 

Symbol name too long 


Symbols are limited to 255 characters. The first character must be alphabetic or 
the underscore character (A-Z, a-z, _). The remaining characters must be alpha¬ 
numeric. includina the underscore character (A-Z. a-z. 0-9. ). 


Symbol tag mismatch 


A matching tag reference could not be found for a tagged symbol table entry. 

Syntax error - expected quote 


The linker was expecting the start of a quoted string. 

Syntax error in address field 


The syntax in a memory file BASE or SECTION record is not correct (possibly 
missing a colon before the address specification). 

Too many buffers in module 
Too many overlays in module 
Too many sections in module 

There is a limit of 255 buffers, 255 overlays, and 255 sections in a single link pro¬ 
cessing phase. 

Unresolved overlay base address 

The symbol used as the runtime overlay address was never resolved during the fix¬ 
up phase. 
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A.5 FATAL ERRORS 
Arithmetic exception 


Appendix A - LINKER 


An internal floating point exception occurred while evaluating an expression. 

Cannot determine file size 

The size of the input link module could not be determined. 

Cannot find GLOBAL section 

The memory control file processing logic could not locate a GLOBAL section 
record. 

Cannot find section record 

The linker was unable to locate a previously accessed section record. This is a se¬ 
rious internal error that should be reported to Motorola. 

Cannot open library file 
Cannot open link file 

The linker attempted to open a library or link file for reprocessing on the second 
pass and the open failed. 

Cannot read file header from library module 
Cannot read file header from object module 

An I/O error occurred which prevented the linker from reading the file headers in a 
library or object file. 

Cannot read line number entries from object module 
Cannot read module string table size 
Cannot read object module section headers 
Cannot read object module string table 
Cannot read object module symbol entries 
Cannot read raw data from object module 
Cannot read relocation entries from object module 

An I/O error occurred which prevented the linker from reading entities in the input 
object file. 

Cannot read optional header from library module 
Cannot read optional header from object module 

An I/O error occurred which prevented the linker from reading the optional headers 
in a library or object file. 
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Cannot seek to library module symbol table 

An I/O error occurred which prevented the linker from positioning correctly when 
attempting to read a library module symbol table. 

Cannot seek to object module line number entries 
Cannot seek to object module raw data 
Cannot seek to object module relocation entries 
Cannot seek to object module section headers 
Cannot seek to object module symbol table 

An I/O error occurred which prevented the linker from positioning correctly in the 
input object file. 

Cannot seek to start of line number entries 
Cannot seek to start of object data 
Cannot seek to start of object file 
Cannot seek to start of section headers 
Cannot seek to start of string table 
Cannot seek to start of symbol table 

An I/O error occurred which prevented the linker from positioning correctly in the 
output object file. 

Cannot set current section 

The current module section map has been corrupted. This is a serious internal er¬ 
ror that should be reported to Motorola. 

Cannot write file header to object file 
Cannot write line number entries to object file 
Cannot write optional header to object file 
Cannot write raw data to object module 
Cannot write relocation entries to object module 
Cannot write section headers to object module 
Cannot write string table to object file 
Cannot write symbols to object file 

An I/O error occurred which prevented the assembler from writing data to the out¬ 
put object file. 

Compare select failure 

The comparison indicator passed to the evaluator selection logic was not valid. 
This is a serious internal error that should be reported to Motorola. 

Counter offset failure 

The offset returned by the linker counter selection logic was not valid. This is a se¬ 
rious internal error that should be reported to Motorola. 
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Current relocation section not available 

A valid relocation section could not be accessed. This is a serious internal error 
that should be reported to Motorola. 

Current section not available 

A valid current section could not be accessed. This is a serious internal error that 
should be reported to Motorola. 

Expression operator failure 

Expression operator lookup has failed. This is a serious internal error that should 
be reported to Motorola. 

Expression stack underflow 

The internal expression evaluation list is out of sequence. This is a serious internal 
error that should be reported to Motorola. 

File contains no relocation information 

An absolute object file was specified as input to the linker. 

Invalid data block type 

Internal section type information has been corrupted. 

Invalid library module header 

An I/O error occurred when attempting to read a library module header. 

Invalid library module header format 

The module header for a file contained in a library has been corrupted. 

Invalid object file for target processor 

Incompatible target processor object files were specified as input to the linker. 

Invalid operand bit size 

The bit size operand in a link file expression was not recognized. 

Invalid section number data 

The section number in a section symbol record is out of range. 

Map option select failure 

The value returned from the mapping selection logic was not valid. This is a seri¬ 
ous internal error that should be reported to Motorola. 
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Offset failure 

An attempt to save the link file offset has failed. 

Ordered section list failure 

Attempting to scan the ordered section list has failed. 

Out of memory - <message> 

There is not enough internal memory to do the operation specified in <message>. 
Since the linker stores all working information in memory, including symbol and 
section information, there is the possibility that memory will be exhausted if many 
symbols or sections are defined in a single linker run. 

Relocation type select failure 

A value returned from the memory control file function select logic is bad. This is 
a serious internal error that should be reported to Motorola. 

Section stack underflow 

The section stacking mechanism has been corrupted internally. 

Seek failure 

An attempt to seek randomly in the link file has failed. 

Space/counter offset failure 

The offset returned by the linker counter selection logic was not valid. This is a se¬ 
rious internal error that should be reported to Motorola. 
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Appendix B 

LIBRARIAN MESSAGES 


B.1 INTRODUCTION 

Librarian messages are grouped into three categories: 

Command Line Errors 

These errors indicate invalid command line options, missing filenames, file open 
errors, or other invocation errors. Command line errors generally cause the librar¬ 
ian to stop processing. 

Warnings 

Warnings indicate that a file cannot be open, or that a module already exists or 
does not exist in the library. The librarian continues processing. 

Fatal Errors 

Fatal errors signify serious problems encountered during library processing such 
as lack of memory, file not found, or other internal errors. The librarian halts imme¬ 
diately. 
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B.2 COMMAND LINE ERRORS 
argument missing 

A necessary argument, such as a module name, was missing from the librarian 
command line. 

unknown option 

The given command line option is not recognized. The librarian continues as if the 
-U option had been given. 
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B.3 WARNINGS 
<module> already in library 

in an add operation a module with the same name as the one specified already ex¬ 
ists in the library. 

<module> not in library 

The named module was not found in the specified library. This error can occur for 
example during a replace operation. 

ambiguous command 

The interactive command issued at the librarian prompt was not unique to the set 
of characters entered. 

cannot open module file 

The named module file could not be open. Either the file does not exist or there 
was an I/O error. 

command requires library name 

All interactive commands require that the library name follow the command name 
on the input line. 

duplicate module name 

The same module name was entered twice on the command line, 
invalid command 

The librarian did not recognize an interactive command. 
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B.4 FATAL ERRORS 

add requires explicit module names 

At least one module name must be given for an add operation. 

cannot allocate argument vector 
cannot allocate copy buffer 
cannot allocate input buffer 
cannot allocate module structure 
cannot allocate module vector 
cannot allocate output buffer 

The librarian did not have enough memory to allocate internal data structures. 

cannot create temporary file name 

The librarian was unable to create a temporary file name for the library scratch file. 

cannot open command file 

The named command line option file does not exist, or there was an I/O error. 

cannot open library file 

The named library file does not exist, or there was an I/O error. 

cannot open temporary file 

An I/O error prevented the librarian from opening the temporary library scratch file. 

cannot read module header 

The librarian could not read the module header in the specified library. Either an 1/ 
O error occurred, or the library file is empty. 

cannot rename <file> 

An error occurred while attempting to rename a library file. 

cannot save command file arguments 

The librarian could not obtain enough memory to store the module names given in 
the command line option file. 

cannot stat module 

The librarian could not obtain date and time information for the named module, 
delete requires explicit module names 

At least one module name must be given for a delete operation. 
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error reading file 

An I/O error occurred while reading a file. 

error writing file 

An I/O error occurred while writing a file. 

fatal errors - <library> not altered 

This is an informative message indicating that the named library was not changed 
because of previous fatal errors. 

file i/o error 

An I/O error occurred while either reading or writing a file. 

improper module header format 

A module header in the library file has been corrupted, or the specified file is not a 
library file. 

library file already exists 

In a create operation the named library file already exists. 

missing command filename 

The required argument on a -F command line option was missing. 
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Appendix C 

LINKER MAP FILE FORMAT 


C.1 INTRODUCTION 

The linker optionally produces a memory map listing file when the command line -M is 
specified. See Chapter 1, RUNNING THE LINKER for more information on command line 
and map listing options. If the -M command line option is given, the map listing goes to 
the file named as the option argument; if no argument is specified, the map listing file 
takes the name of the first object file on the command line and changes the extension to 
.MAP (see Chapter 1). 

C.2 MAP FILE COMMENTARY 

Figure C-1 is a linker-generated map listing of a sample application. The listing illustrates 
a selection of the format and reporting features provided by the linker. The following sec¬ 
tion highlights some of those features. 

At the top of every map listing page is a banner which identifies the linker and lists its ver¬ 
sion number, the date and time of linking, the current input file name, and the page num¬ 
ber. The map file page length, width, and margins can be controlled by the memory 
control file MAP PAGE record (see 1.4.4.3.1, MAP PAGE Modifier). 

The first titled grouping in the report is a list of sections sorted by starting address. This 
list of sections is subdivided by DSP memory such that all X default memory references 
are grouped together, followed by X low memory, X high memory, Y default, and so forth. 
Each line gives the starting address, ending address, and length of every uniquely-named 
section in the linker input stream if that section contained code or data for the current 
memory space. The length reflects the total of all section fragments assimilated from sep¬ 
arate input files. As a result there is only one line for each section even if the section ap¬ 
pears in different files. If sections are located such that they overlap in memory the linker 
will flag the overlap in the map file to the right of the section name. 

A section name may be repeated for a given memory space if that section contains buff¬ 
ers, overlays, or absolute blocks. In this case the start, end, and size of the block is re¬ 
ported and the type of block is placed to the right of the section name. On page 1 of the 
example listing section SECT1 contains a modulo buffer of length 32 starting at address 
20 hexadecimal in X memory. On page 3 of the example the section SECT2 has an over¬ 
lay segment of length 7 that is loaded at address 12 hexadecimal in P memory. The listing 
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of sections by address can be turned off with the memory control file MAP OPT NOSEC- 
ADDR directive (see 1 .4.4.3.2, MAP OPT Modifier). 

The next titled grouping on the map report (page 4) is a list of sections sorted by name. 
The name of the section is given along with the start, end, and length of blocks in each 
DSP memory space. As in the section by address listing special blocks such as buffers 
or overlays are shown on a line by themselves. The section by name report can be dis¬ 
abled by using the memory control file MAP OPT NOSECNAME directive (see 1.4.4.3.2, 
MAP OPT Modifier). 

After the section-oriented reports there appears on page 5 of the map file a symbol listing 
ordered by name. Each line starts with the symbol name (truncated to 16 characters), fol¬ 
lowed by the symbol type (integer or floating point), the memory space if any and value, 
the name of the section in which the symbol is defined, and the symbol attributes. A sym¬ 
bol can be absolute or relative (REL), local, XDEFed (EXTERN), or global, and possibly 
associated with a buffer or overlay. This portion of the map listing may be omitted through 
the memory control file MAP OPT NOSYMNAME directive (see 1.4.4.3.2, MAP OPT Mod¬ 
ifier). 

The last page of the listing shows a symbol listing sorted by value. The listing by value 
can be turned off with the memory control file MAP OPT NOSYMVAL directive (see 
1.4.4.3.2, MAP OPT Modifier). 

The final report group lists the unresolved externals found during the link phase. This con¬ 
sists of all the symbol references for which there was no corresponding definition found in 
the link input. The linker indicates the symbol name and the module in which the refer¬ 
ence was made. 
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Figure C-1 Linker Map Format 
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Figure C-1 Linker Map Format (continued) 
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Figure C-1 Linker Map Format (continued) 
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Figure C-1 Linker Map Format (continued) 
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Figure C-1 Linker Map Format (continued) 
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